Skip to main content

외부 시스템 로그 조회 v2

개요​

API version​

2025-08-19

  • 최초 등록

용도 및 설명​

타 시스템 로그 조회 API (V2)

  1. 사용자가 특정 기간, 조건등의 로그 데이터를 요청
  2. 서버는 로그 데이터를 검색하고 파일로 저장
  3. 로그 데이터를 스트리밍 방식으로 수신

Request​

URI​

MethodsURL
POST/v1/siems/externalSearchV2

URI Parameters​

NameType필수Description

Request Headers​

NameType필수Description
Refererstringtrue라이선스 등록 시 사용된 연동 서비스스 도메인

Request Body​

NameType필수Description
Fromtimestamptrue시작 타임스탬프
Totimestamptrue종료 타임스탬프
Licensestringtrue라이선스 키
orbooleanfalseitems 배열의 결합 방식
false=AND, true=OR
itemsFilterItem[]false포함(positive) 조건 목록
must_notFilterItem[]false제외(negative) 조건 목록
existsstring[]false반드시 존재해야 하는 필드 목록

지원 타입(items[].type)​

타입value 형태설명예시
term단일 값정확 일치(주로 keyword/ip){"name":"logLevel.keyword","type":"term","value":"ERROR"}
terms배열여러 값 정확 일치 중 하나{"name":"event.keyword","type":"terms","value":["A","B"]}
wildcard문자열와일드카드 일치(*/?){"name":"traceId","type":"wildcard","value":"abc*"}
prefix문자열접두 일치{"name":"userId","type":"prefix","value":"kim"}
match문자열텍스트 필드 토큰 기반 검색{"name":"description","type":"match","value":"login failed"}
match_phrase문자열텍스트 필드 문구 일치{"name":"brandName","type":"match_phrase","value":"Hiworks Mail"}

사용가능한 필드 예제​

필드타입 힌트권장 타입Value 예시
ipipterm192.168.1.100
userIdkeywordterm terms prefix wildcarduser123@softcamp.co.kr, admin*
logLevelkeywordterm terms prefix wildcardINFO, ERROR, WARN, DEBUG, TRACE
logTypekeywordterm terms prefix wildcardUSER (사용자 로그), ADMIN (관리자 로그)
brandNamekeywordterm terms prefix wildcardSHIELDGate, Security365 Portal
eventkeywordterm terms prefix wildcardUSER_LOGIN, FILE_DOWNLOAD
(서비스 별 로그 목록 문서에서 이벤트 코드를 참고해주세요.)

Response​

성공 HTTP Status Code 200 Body (JSON 형식)​

NameTypeDescription
Totalint전체 결과 수
Items[]map[string]interface검색 결과 항목들

실패 HTTP Status Code​

HTTP status codeHTTP 메시지설명
400Bad Request요청 정보 오류
401Unauthorized권한 없음
403Forbidden
404Not Found
429Request limit exceeded요청 제한 초과
500Internal Server Error예외발생
66001fail to search검색 실패

Example​

기본 요청​

POST /v1/siems/externalSearchV2
Referer: https://example.com/app
Content-Type: application/json; charset=utf-8

{
    "from": 1755398682000,
    "to": 1755571482000,
    "license": "OZW6-OKGJX-TODB-PLUR4"
}

응답​

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

"total": 3063,
    "items": [
        {
            "_id": "3D2CCD890C413362A53DEE6CD3EFCD993CFA3448B70C84111F642C42A90B39CA",
            "brandName": "SHIELDID",
            "crc32": 2675715286,
            "detail": "{\"errorCode\":0,\"errorMsg\":\"success\",\"taskId\":\"2025/08/18 15:10:01_AZURE_1\",\"status\":\"INPROGRESS\",\"recentTime\":\"2025/08/18 15:10:01\",\"progressPercent\":0,\"progressGroupPercent\":0,\"progressUserGroupPercent\":0,\"code\":0,\"message\":null}",
            "description": "Request a code method token",
            "event": "POST_MIGRATE_GET_LATEST_USER_SYNC_TASK_INFO",
            "id": "3EAD7E3FD71BC59A56136DFE3A60A32ED129D9363B1DA29BAC9C22274194537A",
            "inserttime": "2025-08-19 02:44:40.944",
            "ip": "10.10.32.47",
            "logLevel": "INFO",
            "logType": "ADMIN",
            "serviceHostname": "cloud-idgpmig-service-7cd4c45f5f-dkr5k",
            "serviceId": "7e0ade63-1fa2-41ae-8cad-dbfa65d637af",
            "serviceName": "IDGPMIGRATION",
            "sort": [
                1755571480950,
                "3D2CCD890C413362A53DEE6CD3EFCD993CFA3448B70C84111F642C42A90B39CA"
            ],
            "target": "2025/08/18 15:10:01_AZURE_1",
            "tenantId": "3CJ55MSE-xLO7Sxt4-qUBKzbcs-XP2cgGEq",
            "time": 1755571480950,
            "traceId": "1060-c473b7c2-0b3a-4504-83be-f96c9a7e79c4",
            "userId": "user1@socam.info"
        }, .... + 3062

조건 요청(1)​

POST /v1/siems/externalSearchV2
Referer: https://example.com/app
Content-Type: application/json; charset=utf-8

{
    "from": 1755398682000,
    "to": 1755571482000,
    "license": "OZW6-OKGJX-TODB-PLUR4",
    "filters": {
    "or": false,
    "items": [
      { "name": "logLevel.keyword", "type": "term", "value": "ERROR" },
      { "name": "brandName.keyword", "type": "term", "value": "SHIELDRM"}
    ]
  }
}

조건 요청(2)​

POST /v1/siems/externalSearchV2
Referer: https://example.com/app
Content-Type: application/json; charset=utf-8

{
    "from": 1755398682000,
    "to": 1755571482000,
    "license": "OZW6-OKGJX-TODB-PLUR4",
    "filters": {
        "or": false,
        "exists": [
            "userId"
        ],
        "must_not": [
            {
                "name": "logType.keyword",
                "type": "term",
                "value": "USER"
            }
        ]
    }
}

응답​

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

"total": 2,
"items": [
    {
            "_id": "1B9BBE7150516DBBF4D99256DF6566505342776E5F241579DC4746EE5D079116",
            "brandName": "SHIELDRM",
            "corp": {
                "id": "3CJ55MSE-xLO7Sxt4-qUBKzbcs-XP2cgGEq",
                "openId": [
                    {
                        "oauthType": "AZURE",
                        "tenantInfo": "4d615af9-1d04-4bcc-8e6f-c6b6fe3110dd"
                    }
                ]
            },
            "crc32": 2959976420,
            "description": "Monitored document conversion failed",
            "detail": "Task Monitoring url failed : MonitoringResponse.ErrorResponse(code=fileNotFound, message=Sensitivity label cannot be assigned to the given file as the file is not available.)",
            "event": "MONITORING_CONVERT_DOC_FAIL",
            "file": {
                "ext": "xlsx",
                "name": "101.xlsx",
                "status": "SHIELDRM_EXCP",
                "type": "normal",
                "typePrev": "aip",
                "typePrevDetail": "e1069f39-642f-44de-a08a-482d5fffb495"
            },
            "id": "07DAFFDC98F9C922F344C1AB476A659C2CFB4D0C5D2C09C2C254B74FAF29A025",
            "inserttime": "2025-08-19 01:20:21.406",
            "ip": "10.42.5.74",
            "logLevel": "ERROR",
            "logType": "USER",
            "profile": "{\"SHIELDRM_PROC\":1,\"SHIELDRM_PEND\":1}",
            "serviceHostname": "cloud-ssevtr-service-6b9b76587b-c5vs2",
            "serviceId": "144b38de-5cd4-44ac-a389-842d13995f67",
            "serviceName": "ssevtr",
            "sort": [
                1755566420263,
                "1B9BBE7150516DBBF4D99256DF6566505342776E5F241579DC4746EE5D079116"
            ],
            "storage": {
                "id": "69f3bff3-e931-4846-bb3c-700ccb98ad07",
                "storageCode": "teams",
                "url": "https://socamresearch.sharepoint.com/sites/shieldrmtest61"
            },
            "target": "101.xlsx",
            "taskId": "ITEMADDED:69f3bff3-e931-4846-bb3c-700ccb98ad07:a6ba2e18-99ec-49ea-b0c7-711460c4bdb7:4d615af9-1d04-4bcc-8e6f-c6b6fe3110dd:admin@socam.info",
            "tenantId": "3CJ55MSE-xLO7Sxt4-qUBKzbcs-XP2cgGEq",
            "time": 1755566420263,
            "traceId": "SHIELDRM-870343b8-3760-459f-bbdb-333faa47e11d",
            "urlFile": {
                "event": "added",
                "itemId": "a6ba2e18-99ec-49ea-b0c7-711460c4bdb7",
                "siteId": "69f3bff3-e931-4846-bb3c-700ccb98ad07",
                "siteType": "teams",
                "url": "https://socamresearch.sharepoint.com/sites/shieldrmtest61"
            },
            "user": {
                "id": "admin@socam.info"
            },
            "userId": "admin@socam.info"
        }, .... + 1

주요 응답 필드 설명​

keytypevalue
traceIdstring서비스간 흐름을 추적하기 위한 ID
timetimestamp로그생성시간 (millisecond)
ipstring로그 생성 IP
userIdstring로그 관련 사용자 ID
logLevelstringERROR, WARN, INFO, DEBUG, TRACE
logTypestringAPP, ADMIN, USER 등
brandNamestring서비스 이름 (예, SHIELDGate, Security365 Portal)
tenantIdstring인증인가에 등록된 고객사 ID
targetstring이벤트와 관계된 파일명, 사용자, URL 등 연관 정보
eventstring이벤트 코드 문자열 (서비스 별 로그 목록 문서에서 이벤트 코드 참고)
descriptionstring이벤트 상세 설명 (표현용 문자열)